The game module declaration supplies information about the file as a whole. It is optional; if missing, Xconq will get the module's name from its file name, and supply defaults for the other properties.
Form: game-module [ name ] properties...
This form defines the properties of this game module.
The optional name is a string that will be used to look up
the module in libraries.
If the name is supplied, then this form is considered to be the
definition of the module, and overwrites any
game-module form previously appearing in this file.
If name is missing, then this form will modify the
existing description of the module.
Although are currently no restrictions enforced on the length or
character set of a module name, Xconq may warn about a name
that does not match the name of the file containing these forms;
see See section Files and Directories for more detail.
ModuleProperty: title string
If defined, this property is the name by which the module will be displayed to players. It is not used internally, so the name can be modified freely (unlike the module's name, which may appear in other modules). Defaults to the module's name.
ModuleProperty: blurb string
This property is a one-line description that users will see when they are deciding whether to play the module. It will be displayed without any modification:
Welcome to my nightmare! (version 1.0 with stronger goblins)
ModuleProperty: picture-name string
This property is the name of a picture that may be displayed along with the module's blurb, by those interfaces that support such pictures.
ModuleProperty: base-game t/f
ModuleProperty: instructions strings...
This property is a list of strings that are the instructions on how to play the game.
ModuleProperty: notes strings...
This property is a list of strings comprising the set of detailed player's notes for the module. Both the list and each string in the list can be of any length. When displayed, the strings are all concatenated together, so the division into strings here is just for convenience. How these are displayed is up to the interface, but in general an empty string signals a new paragraph.
ModuleProperty: design-notes strings...
This property is a list of strings that are notes addressed to game designers.
ModuleProperty: version string
This property is the version of the module.
Defaults to "",
which indicates that the module's version is undefined.
ModuleProperty: program-version versions
This property dentifies Xconq versions for which this module
is appropriate.
If specified, then players will get a warning if they attempt to use this
module with an inappropriate version of Xconq.
Possible forms include a string, which allows the module only for
exactly matching version of Xconq,
and (comparison version),
which allows versions satisfying the comparison test,
which may only be >= or <=.
So for instance
(game-module "foo" (program-version (>= "7.0.3")))
is claimed to only work for versions 7.0.3 or later.
Defaults to "", which means that the module is appropriate for
any version of Xconq.
Notes that the program-version is strictly a heuristic to forewarn
players; in practice it can be very difficult to know which modules work
with which programs. (The problems are similar to those encountered
by programmers using different compiler versions on their programs.)
ModuleProperty: base-module name
This property is the name of a module that must be loaded first.
It is similar in effect to include.
ModuleProperty: default-base-module name
This property specifies the name of a module that will be loaded
if this module is given as the "top-level" module,
such as via -g on a command line.
This is to prevent disasters when a library module that is used only by other modules is instead loaded as if it were a full game design.
ModuleProperty: original-module name
ModuleProperty: original-version string
ModuleProperty: original-variants list
These properties record the module's name, version, and variant selections before a game save. They are needed to record the game in the scorefile usefully.
Variants are options chosen by players at the start of a game. A generic variant includes information that will be used for displaying the choice to players, the acceptable range of choices, a default choice, and additional forms that may be evaluated if particular values were chosen. Variant values are always numbers.
ModuleProperty: variants items...
This property defines named variants on this module.
Variants appear as startup options for the game.
The items have the form
([ name ] type [ range/default ] [ clauses ]).
The name is a string or symbol used to identify the choice to
the players, the type says what sort of change is being enabled,
range/default supplies a range of values and a default value
among them,
and clauses is a list of the form (value forms....
A game module may specify any number of variants.
Defaults to ().
A number of commonly useful variant types are predefined.
VariantType: world-size [ width [ height [ circumf [ lat [ lon ] ] ] ] ] [ clauses ]
This variant allows players to choose the size of the world.
The sizes will default to the values in this variant's data.
(width and height can be lists of the form (lo dflt hi),
with the obvious interpretation??)
VariantType: world-seen [ dflt ] [ clauses ]
This variant allows players to choose whether
the terrain of the world will be known at the start of the game.
The default setting will be the value dflt,
which may be either true or false.
VariantType: see-all [ dflt ] [ clauses ]
This variant allows players to choose whether everything will be seen
always, as with the global variable see-all.
The default is set by dflt.
VariantType: sequential [ dflt ] [ clauses ]
This variant allows players to choose whether to move simultaneously during a turn, or one at a time. The default is set by dflt.
VariantType: real-time [ total [ perside [ perturn ] ] ] [ clauses ]
This variant allows players to choose realtime limits on the game. The value will default to the values in this variant's data.
You can include one game module in another.
Form: include module-name [ variant-settings ]
This form has the effect of inserting the contents
of module-name into the current position in the module.
game-module forms in the included module are not inserted,
although they are remembered and may appear in displays.
Xconq will fail completely if the included module cannot be found.
Unlike C etc, the same module cannot be included more than once; you will get a warning and the module will not be loaded.
Note that the module names are not file names, so that system-specific features like directories and devices cannot be included. The mapping between module name and file name is interface-specific, so if you want to distribute a module, you should make sure all the module names don't have anything nonportable embedded. Alphanumeric characters and hyphens are guaranteed to be portable; mixed-case names are not.
You can control which forms in a module are actually evaluated by using conditional loading.
Form: if test-form sym
If test-form evaluates to true,
then all subsequent forms, up until the matching else
or end-if, will be evaluated.
If false, then the forms will be read but not evaluated.
All forms inside the conditional must be syntactically correct.